Copyright: (c) November 1998, Robert Galle


Introduction
WhereIsIt's Description API

Programmer's Reference

Welcome to the WhereIsIt's Description Application Programming Interface (Description API), a special feature available to programmers to extend WhereIsIt's capabilities with automatic description importing. For all those new to programming, API is a standardized set of functions and procedures that allow both master program and extension library to communicate. With Description API, your end result will be a DLL library implementing functions described here, therefor allowing itself to integrate in WhereIsIt application.


Basic Concepts

Description plugins in WhereIsIt are in form of 32-bit Dynamic Link Libraries (DLL files). You can write and compile a DLL with most Windows programming Languages available today. All of your DLL library functions that are either exported or sent as parameters to WhereIsIt must use the __stdcall calling convention for passing their own parameters.

There are two basic concepts involved while preparing a Description API compliant DLL:

Description Module

A description module is equal to single DLL file. Each module can include one or more description plugin, and WhereIsIt can accept multiple description modules to work with at the same time. All communications defined in Description API are between WhereIsIt and description module.

Description Plugin

A description plugin is a part of module that is capable of importing descriptions from one specific description source - for example, File_id.diz files. Each description module will handle its own plugins, and take care about their registration and communicating with WhereIsIt.

During description module initialization each module will be called to present itself and register available plugins with WhereIsIt. This way, program can manage list of available description plugins, presenting them to user in order to assign import priority, or to enable or disable them. Later, when a description source is found during disk scan that can be handled by one of registered plugins, its parent module is called with request to provide description from that plugin.


Description Plugin Types
Description Plugins Types

Because of there are different ways how to get a description from different sources, Description API includes definitions about different types of plugins. While all plugins have a goal to eventually produce a description to be used in WhereIsIt, communication with the main program with differ based on how they can get those descriptions. Each plugin group has its own ID, as defined in Description API:

ptReserved

Plugins of type ptReserved are for WhereIsIt's internal use only. Do not use ptReserved plugin type in your own description modules.

ptSameFile

This is the simplest group of plugins. Plugins of this type can extract description from the same file or folder that will be described in catalog with this description. In other words, file contains description for itself, and plugin will extract it and report it back. Examples of such files could be graphics or audio files - a plugin could return their size, color depth, play length etc. as a description. Plugin will receive the file as a parameter, for which it is expected to return a suitable description.

Import function: ImportDesc_SameFile

ptParentItem

This group of plugins will return a description from given source file for a parent item, usually a folder where they are located, or an archive file, if source file is compressed inside. A typical example of this group are well known FILE_ID.DIZ files. When description is needed, a plugin of this type will receive a list of all files registered for importing description for their parent item. If more than one such file is available, it is up to the plugin to decide which one to use.

Import function: ImportDesc_ParentItem

ptItemList

This group can provide multiple descriptions from the same source, and is targeted to such description files that hold a list of descriptions for files and folders on media, either in same folder as description file itself, or in subfolders as well. Examples of such description files are FILES.BBS, DESCRIPT.ION, 00INDEX.TXT etc., each holding descriptions for items in the same folder. When plugin of this type is called, it will receive a list of found description files of this type, and an address of function where it will report back each file-description pair it was able to get from the source file(s).

Import function: ImportDesc_ItemList

ptDiskInfo

Plugins in this group can be used to describe media itself based on its properties, like type, size, serial number, etc. A plugin of this group will receive as a parameter a record off all known details about media. An example that comes to mind would be Audio CD recognition, perhaps even by using one of public Audio CD databases on the Internet.

Import function: ImportDesc_DiskInfo


Description API Functions

This is the list of all available functions defined in Description API in order to provide a way for WhereIsIt and description module to communicate. Some of these functions are required to be present and exported in description module, while some are optional. Function set has been kept as minimal as possible, in order to simplify programming of plugins. Programmer should be able to keep focus on how to get description from required source while WhereIsIt will take care of the rest.

Description Module Initialization

ModuleInfo	( required )

RegisterDescPlugins	( required )

ConfigPluginProc	( optional )

Description Importing

InitDescImport	( optional )

DoneDescImport 	( optional )

ImportDesc_SameFile	( required if plugins of type ptSameFile are registered )

ImportDesc_ParentItem	( required if plugins of type ptParentItem are registered )

ImportDesc_ItemList	( required if plugins of type ptItemList are registered )

ImportDesc_DiskInfo	( required if plugins of type ptDiskInfo are registered )

Callback functions

RegisterPlugin	( callback )

RequireFile	( callback )

StoreDescProc	( callback )

Legend:

required functions must be present and exported in your DLL in order to be used in WhereIsIt. WhereIsIt will not accept DLL missing those functions as a valid description module.

optional functions are provided for your convenience and will be called from WhereIsIt if they are exported in your DLL. You can use them if you need them with description importing.

callback functions are defined in WhereIsIt, their addresses will be passed to one of your DLL-defined functions as parameters. Those functions are provided for description modules to pass back information to WhereIsIt, or to employ some of WhereIsIt's capabilities during description importing.


Description API Structures

The following constants and structures are defined as a part of Description API:

Structures

DISKINFORECORD

Constants

PluginType

MaxDescLength

DriveTypes


ModuleInfo
 ModuleInfo()

REQUIRED

The ModuleInfo function is the first one called by WhereIsIt when collecting data about available plugins. This function will present your Description module's name, author, and version to WhereIsIt. A function with this name must be exported from your DLL file for WhereIsIt to accept it as a description module.

  VOID ModuleInfo(

    LPTCSTR lpszModuleName,	// address of buffer to store module name

    LPTCSTR lpszAuthor,	// address of buffer to store author's name

    LPTCSTR lpszVersion	// address of buffer to store version string

  );

Parameters

lpszModuleName

Points to the buffer to receive the null-terminated string containing the module's name. String may not exceed 1024 bytes in length. Example: 'WhereIsIt Description Module'.

lpszAuthor

Points to the buffer to receive the null-terminated string containing the author's name. String may not exceed 1024 bytes in length. Example: 'Robert Galle'.

lpszVersion

Points to the buffer to receive the null-terminated string containing the version number. String may not exceed 1024 bytes in length. Example: '0.90 beta'.

Return Values

None.

Remarks

If any of strings is returned empty, WhereIsIt will not register or use this module.


RegisterDescPlugins
 RegisterDescPlugins()

REQUIRED

The RegisterDescPlugins function is called during module initialization. Description module is expected to provide WhereIsIt with information about available description plugins in this module. The RegisterDescPlugins function receives as a parameter the address of callback function to be used for registering plugins. A function with this name must be exported from your DLL file for WhereIsIt to accept it as a description module.

  VOID RegisterDescPlugins(

    PROC lpRegisterPlugin	// pointer to a callback function

  );

Parameters

lpRegisterPlugin

Points to address of WhereIsIt-defined function to call when registering a new plugin. See the RegisterPlugin function description for details.

Return Values

None.

Remarks

You may want to store the address of lpRegisterPlugin callback procedure in case you will need it later, too. You can call again this procedure to re-register plugin in WhereIsIt in case some of data has changed - for example, plugin can have a configure dialog where user can change some details about the plugin.

See also:

RegisterPlugin


ConfigPluginProc
 ConfigPluginProc()

OPTIONAL

The ConfigPluginProc is a function provided inside description module, and provides everything necessary for user to configure specified plugin - create and show appropriate dialog, load and store settings etc. Each plugin in description module can have assigned its own config function, or some of them (or all) can share the same one. Config function for each plugin is specified as a part of plugin registration, using the RegisterPlugin function.

  VOID ConfigPluginProc(

    HINSTANCE hInstance,	// handle to application instance

    HWND hWndParent,	// handle to parent or owner window

    WORD wPluginID	// ID of plugin to configure

  );

Parameters

hInstance

Identifies the instance of the module to be associated with the window.

hWndParent

Identifies the parent or owner window of any window, created by config function.

wPluginID

Contains plugin ID number to be used as a reference to this plugin. When WhereIsIt will call one of description importing functions provided by your plugin, and request that specific plugin is used, this ID will be used to specify the plugin. Each plugin must have an unique ID code assigned inside your module, with valid values of 0 - 65535. Recommended is sequential numbering from 0 forward.

Return Values

None.

Remarks

If your config procedure(s) need place to store their settings, you can use a special key in  the registry. This key is reserved for all plugins used in WhereIsIt - each plugin should create its own key under Settings to store the data:

HKEY_CURRENT_USER\SOFTWARE\SearchSoft\Where Is It?\Plugins\Settings

See also:

RegisterPlugin


InitDescImport
 InitDescImport()

OPTIONAL

The InitDescImport is optional and only called if your description module exports a function by this name. It does not have any parameters, and does not return any result - this is just a way for WhereIsIt to notify all interested description modules that disc scan operation is just about to begin. If any of your plugins need to be initialized or prepared in some other way before they can start importing, this is the place to do it.

  VOID InitDescImport(VOID);

Parameters

None.

Return Values

None.

See also:

DoneDescImport


ImportDesc_SameFile
 ImportDesc_SameFile()

OPTIONALLY REQUIRED

The ImportDesc_SameFile function is the main import function for plugins of type ptSameFile. WhereIsIt will call this function during disk scan every time when a file is found that matches the file mask of one of ptSameFile plugins in your module. WhereIsIt will expect from this function to do required processing on provided file (using requested description plugin), and return appropriate description.

  BOOL ImportDesc_SameFile(

    WORD wPluginID,	// ID of description plugin to be used with provided file

    LPTCSTR lpszFileName,	// points to null-terminated string with full path to file

    LPTSTR lpszDesc,	// address of buffer to receive description

    PROC lpRequireFileProc	// address of RequireFile callback function

  );

Parameters

wPluginID

Contains the ID number of plugin that must be used to extract description from given file. If there are more plugins of type ptSameFile registered in your description module, then the ImportDesc_SameFile function must check the wPluginID parameter and activate the proper plugin.

lpszFileName

Points to the null-terminated string, containing the full path to the file, waiting to be described. Provide this parameter to the RequireFile function before your plugin attempts to open the file.

lpszDesc

Points to the buffer (reserved by WhereIsIt) to receive null-terminated string with the description.

WARNING: Make sure that length of your description copied to this buffer does not exceed maximum allowed size for descriptions (provided in MaxDescLength global constant, currently set to 4 kB). If description is longer, it is likely to cause severe errors in program!

lpRequireFileProc

This is the address of RequireFile callback function. Before your plugin may access the file provided with lpszFileName parameter, RequireFile function must be called, and path returned by this function used to access the file.

Return Values

Function should return TRUE if description was successfully retrieved and stored lpszDesc, or FALSE, if retrieving description was not successful.

Remarks

If this function returns FALSE, or returned description is empty, WhereIsIt will try to find another plugin of the same type that can also be used to get description for current item, but has lower priority set than the plugin just called.

See also:

Plugins types, RequireFile


ImportDesc_ParentItem
 ImportDesc_ParentItem()

OPTIONALLY REQUIRED

The ImportDesc_ParentItem function is called by WhereIsIt when program needs to import description from one of module's ptParentItem plugins, and some of found files are matching plugin's file mask. Plugin will receive a list of matching files, and is expected to extract description to be assigned to the parent item (usually a parent folder, or an archive file, where found files are compressed in).

  BOOL ImportDesc_ParentItem(

    WORD wPluginID,	// ID of description plugin to be used with provided file

    LPTCSTR lpszParentName,	// points to null-terminated string with parent item's path

    LPTCSTR lpszFileList,	// points to a double - null-terminated list of found files

    LPTSTR lpszDesc,	// address of buffer to receive description

    PROC lpRequireFileProc	// address of RequireFile callback function

  );

Parameters

wPluginID

Contains the ID number of plugin that must be used to extract description from given file. If there are more plugins of type ptParentItem registered in your description module, then the ImportDesc_ParentItem function must check the wPluginID parameter and activate the proper plugin.

lpszParentName

Points to the address of a null-terminated string, holding the full path to parent item (item that will receive description provided by calling this function).

lpszFileList

Points to the address of a double - null-terminated list of file names. These are files that were found in current folder matching the file mask of requested plugin (for example, if plugin has a mask of "*.TXT", this is the list of all .TXT files found in current folder). List is in form of sequential null-terminated strings, with double NULL character after the last item, i.e.:

  FILE1.TXT#0FILE2.TXT#0FILE3.TXT#0#0

where "#0" represents a NULL character. It is up to plugin to choose which file will it use to import description from. Provide the name of chosen file(s) to the RequireFile function before your plugin attempts to open the file. Files in the list are sorted in the same order as are plugin's mask, preserving priorities. For example, if plugin is set to import "*.aaa,*.bbb" files, all aaa files will be listed first, followed by all bbb files.

lpszDesc

Points to the buffer (reserved by WhereIsIt) to receive null-terminated string with the description.

WARNING: Make sure that length of your description copied to this buffer does not exceed maximum allowed size for descriptions (provided in MaxDescLength global constant, currently set to 4 kB). If description is longer, it is likely to cause severe errors in program!

lpRequireFileProc

This is the address of RequireFile callback function. Before your plugin may access the file provided with lpszFileName parameter, RequireFile function must be called, and path returned by this function used to access the file.

Return Values

Function should return TRUE if description was successfully retrieved and stored lpszDesc, or FALSE, if retrieving description was not successful.

Remarks

If this function returns FALSE, or returned description is empty, WhereIsIt will try to find another plugin of the same type that can also be used to get description for current item, but has lower priority set than the plugin just called.

See also:

Plugins types, RequireFile


ImportDesc_ItemList
 ImportDesc_ItemList()

OPTIONALLY REQUIRED

The ImportDesc_ItemList function is a front-end for ptItemList - typed plugins. This function will be called by WhereIsIt when some of files are found to match the plugin's file mask, and plugin is given a chance to import descriptions from them. Since plugins of this type can retrieve multiple description from the source, a callback function is provided for a plugin to report the extracted descriptions back to WhereIsIt.

  VOID ImportDesc_ItemList(

    WORD wPluginID,	// ID of description plugin to be used with provided file

    LPTCSTR lpszParentName,	// points to null-terminated string with parent item's path

    LPTCSTR lpszFileList,	// points to a double - null-terminated list of found files

    PROC lpRequireFileProc,	// address of RequireFile callback function

    PROC lpStoreDescProc	// address of StoreDescProc callback function

  );

Parameters

wPluginID

Contains the ID number of plugin that must be used to extract description from given file. If there are more plugins of type ptParentItem registered in your description module, then the ImportDesc_ItemList function must check the wPluginID parameter and activate the proper plugin.

lpszParentName

Points to the address of a null-terminated string, holding the full path to parent item (parent folder or compressed archive file holding the found files).

lpszFileList

Points to the address of a double - null-terminated list of file names. These are files that were found in current folder matching the file mask of requested plugin (for example, if plugin has a mask of "*.TXT", this is the list of all .TXT files found in current folder). List is in form of sequential null-terminated strings, with double NULL character after the last item, i.e.:

  FILE1.TXT#0FILE2.TXT#0FILE3.TXT#0#0

where "#0" represents a NULL character. It is up to plugin to choose which file will it use to import description from. Provide the name of chosen file(s) to the RequireFile function before your plugin attempts to open the file.

lpRequireFileProc

This is the address of RequireFile callback function. Before your plugin may access the file provided with lpszFileName parameter, RequireFile function must be called, and path returned by this function used to access the file.

lpStoreDescProc

Holds the address of StoreDescProc callback function, used to report descriptions back to WhereIsIt. See the description of StoreDescProc for more details.

Return Values

None.

See also:

Plugins types, RequireFile, StoreDescProc


ImportDesc_DiskInfo
 ImportDesc_DiskInfo()

OPTIONALLY REQUIRED

The ImportDesc_DiskInfo function is called for plugins of ptDiskInfo type. Function receives as a parameter an address to DISKINFORECORD structure, containing many details about media, such as media type, size, volume label, serial number etc. The plugin may want to access some other source to retreive more detailed data about the media, such as network server, or even Internet based database.

  BOOL ImportDesc_DiskInfo(

    WORD wPluginID,	// ID of description plugin to be used for importing

    LPDISKINFOREC lpDiskInfo,	// points to the DISKINFORECORD structure

    LPTSTR lpszDesc	// address of buffer to receive description

  );

Parameters

wPluginID

Contains the ID number of plugin that must be used to extract description from given file. If there are more plugins of type ptParentItem registered in your description module, then the ImportDesc_DiskInfo function must check the wPluginID parameter and activate the proper plugin.

lpDiskInfo

Points to the DISKINFORECORD structure, containing details about media that is being scanned.

lpszDesc

Points to the buffer (reserved by WhereIsIt) to receive null-terminated string with the description.

WARNING: Make sure that length of your description copied to this buffer does not exceed maximum allowed size for descriptions (provided in MaxDescLength global constant, currently set to 4 kB). If description is longer, it is likely to cause severe errors in program!

Return Values

Function should return TRUE if description was successfully retrieved and stored lpszDesc, or FALSE, if retrieving description was not successful.

Remarks

If this function returns FALSE, or returned description is empty, WhereIsIt will try to find another plugin of the same type that can also be used to get description for current item, but has lower priority set than the plugin just called.

See also:

Plugin types, DISKINFORECORD


DoneDescImport
 DoneDescImport()

OPTIONAL

The DoneDescImport is optional and only called if your description module exports a function by this name. WhereIsIt will call this function when disk scanning has completed, and this function provides a way to clean up after plugins have done their job.

  VOID DoneDescImport(VOID);

Parameters

None.

Return Values

None.

See also:

InitDescImport


RegisterPlugin
 RegisterPlugin()

CALLBACK

The RegisterPlugin function is provided by WhereIsIt, and is received as a parameter with the RegisterDescPlugins function. Your module will call RegisterPlugin from the RegisterDescPlugins function, once for each description plugin available in your module. Parameters to this function will provide everything WhereIsIt needs to know about the specified plugin.

  INT RegisterPlugin(

    WORD wPluginID,	// unique plugin's ID inside your description module

    BYTE byPluginType,	// specifies plugin type

    LPTCSTR lpszPluginMask,	// address of buffer to store plugin's target file masks

    PROC lpConfigProc	// address of function used to configure plugin

  );

Parameters

wPluginID

Contains plugin's ID number to be used as a reference to this plugin. When WhereIsIt will call one of description-importing functions provided by your plugin, and request that specific plugin is used, this ID will be used to specify the plugin. Each plugin must have an unique ID code assigned inside your module, with valid values of 0 - 65535. Recommended is sequential numbering from 0 forward.

byPluginType

Specifies the type of plugin.

lpszPluginMask

Points to the null-terminated string containing the list of file or file masks. This is the list of files that your plugin can extract description(s) from. For example, a plugin that can extract information from WAV files and use it to describe those file will provide "*.WAV" as a plugin mask. If during disk scan one or more files complying with specified mask are encountered, your plugin will be called to extract description from them. Files or file masks in string should be provided in UPPER-CASE and separated with commas. Example: "README.TXT, *.NFO". This parameter is required for all plugin types except ptDiskInfo, where you can set it as NULL.

lpConfigProc

Points to the function that can be used to setup your plugin. This function will be called if user will select your plugin in WhereIsIt, and click the Configure button. If your plugin does not provide users with ability to configure the plugin, you can specify NULL here as a parameter.

Return Values

If returned value is equal or greater to zero, plugin was successfully registered with WhereIsIt and return value represents plugin's assigned serial number on WhereIsIt's plugin list. This value is informative only, you may safely discard it.

Negative return value is an error code, by the following table:

-1	Invalid plugin type

-2	Plugin with this ID already exists in your module

-3	The name of plugin is invalid

-4	File mask provided for plugin is invalid

-5	Module does not export required description function for this plugin type

Note that error code -2 only applies if trying to register a plugin of different type than the one already registered with the same ID. If both plugins have the same ID and are of the same type, WhereIsIt will adjust settings for existing plugin instead of registering a new one.

See also:

RegisterDescPlugins, plugin types


RequireFile
 RequireFile()

CALLBACK

The RequireFile function is provided by WhereIsIt, and is used by plugins whenever they need to access a specific file. The address of this function to call is provided as a parameter to each of description importing functions - ImportDesc_xxx. Function will return a new string, containing a full path to the requested file that plugin can now actually open and use.

The main purpose of this function is to unpack description files, if they are compressed inside archives. If such compressed file is requested by plugin via RequireFile function, WhereIsIt will first unpack it to temporary folder, and return the full path to the uncompressed file. Temporary files will be removed as soon as the plugin is finished with importing current description and returns control back to WhereIsIt.

  LPTSTR RequireFile(

    LPTCSTR lpszFileName	// path to file to access

  );

Parameters

lpszPluginMask

Points to the null-terminated string containing a path to file that plugin would like to use. Path to file should be the same one as provided by WhereIsIt to the ImportDesc_xxx function.

Return Values

Returns a pointer to null-terminated string, containing full path to the requested file that plugin can use. This path is not necessary the same as the one provided as parameter to this function.

Remarks

Make sure that you use this function to request access to any file used by the plugin during description importing.

See also:

ImportDesc_SameFile, ImportDesc_ParentItem, ImportDesc_ItemList


StoreDescProc
 StoreDescProc()

CALLBACK

The StoreDescProc function is provided by WhereIsIt, and its address is sent as a parameter to the ImportDesc_ItemList function. The latter is used to import description using ptItemList plugins, meaning it will possibly return multiple descriptions from single description source. The purpose of StoreDescProc function is to provide a way for ImportDesc_ItemList function to send each retrieved file name-description pairs back to WhereIsIt, where it will be stored in the database.

  BOOL StoreDescProc(

    LPTCSTR lpszFileName,	// points to retrieved file name

    LPTCSTR lpszDesc	// points to retrieved description string

  );

Parameters

lpszFileName

Points to the null-terminated string containing name and optional path to file or folder. WhereIsIt will try to find this item among catalogued data, and attach to it the description provided as the next parameter. See Remarks below for additional details.

lpszDesc

Points to the null-terminated string containing a description retrieved by plugin that belongs to the lpszFileName parameter.

WARNING: Length of provided description should not exceed the maximum allowed description size, limited by MaxDescLength global constant (currently set to 4 kB). If description is longer, it will be truncated.

Return Values

Returns TRUE if description was successfully stored in catalog, or FALSE, if provided file name was not found in the catalog.

Remarks

File or folder name can be provided in any of these three forms: name only, name with relative path from current folder, or file name with full path to item on the disk.

• If target item is located in the same folder as description file is, you should provide the lpszFileName parameter as plain file name only, for example "TEST.EXE". This is also the most optimal choice from performance point of view since program is optimized to quickly find items in current folder. Most of description file formats like INDEX.TXT or FILES.BBS include list of files for current folder only, so you should be able to use this mode as much as possible.

• If target is located in one of subfolders, relative to folder with the description file, you can use addressing with relative path, for example "FOLDER1\FOLDER2\...\TEXT.EXE". WhereIsIt will start in the current folder and look in catalog for subfolder named Folder1. If provided subfolder exist in catalog, WhereIsIt will look for file, too, and append description if file is found.

• If you would like to provide descriptions for items anywhere on the disk, you will have to provide full path to the target file, including the drive letter, for example "F:\CURRENT\FOLDER1\FOLDER2\TEST.EXE".

WARNING: This mode is only allowed when user is importing descriptions on demand, in already catalogued data, and will always fail when you try to use it during the disk scan.

Note: The last two modes can be considerably slower compared to the first one, especially if there are many subfolders in the disk you are scanning. If there are many items to import, end user may be experiencing a long delay.

See also:

ImportDesc_ItemList


 MaxDescLength

The MaxDescLength constant defines the maximum allowed description length for items in WhereIsIt's catalogs.

#define MAXDESCLENGTH  4096     // maximum allowed description length in bytes

WARNING: Description plugins may not exceed description length when preparing descriptions, or they can cause severe errors in the program.

See also:

ImportDesc_SameFile, ImportDesc_ParentItem, ImportDesc_ItemList, ImportDesc_DiskInfo, StoreDescProc


DriveTypes
 Drive Type Constants

This is the list of currently supported drive and media types in WhereIsIt:

#define DT_FLOPPY525_360     0     // floppy 5.25" 360 kB

#define DT_FLOPPY525_12      1     // floppy 5.25" 1.2 MB

#define DT_FLOPPY35_720      2     // floppy 3.5" 720 kB

#define DT_FLOPPY525_8SD     3     // floppy 8" Single Density

#define DT_FLOPPY525_8DD     4     // floppy 8" Double Density

#define DT_HARDDISK          5     // hard disk

#define DT_TAPEDRIVE         6     // tape drive

#define DT_FLOPPY35_144      7     // floppy 3.5" 1.44 MB

#define DT_OPTICAL           8     // optical drive

#define DT_FLOPPY35_288      9     // floppy 3.5" 2.88 MB

#define DT_CDROM             10    // CD-ROM

#define DT_NETWORK           11    // Network drive

#define DT_RAMDISK           12    // RAM disk

#define DT_REMOVABLE         13    // generic removable drive

#define DT_ZIPDRIVE          14    // iomega ZIP 100

#define DT_JAZDRIVE          15    // iomega JAZ 1GB

#define DT_ZIPDRIVEPLUS      16    // iomega ZIP 100 Plus

#define DT_SEAGATEDIRECTTAPE 17    // Seagate Direct Tape virtual drive

#define DT_LS120             18    // LS-120 floppy drive

#define DT_MOS320            19    // Deltis MOS320 removable drive

#define DT_MOS332            20    // Olympus MOS332 removable drive

#define DT_M2531A            21    // Fujitsu M2531A removable drive

#define DT_JAZ2DRIVE         22    // iomega JAZ 2GB

#define DT_UNKNOWN           255   // unknown drive

See also:

DISKINFORECORD, ImportDesc_DiskInfo


 DISKINFORECORD

The DISKINFORECORD structure is used with ImportDesc_DiskInfo function.

typedef struct {

  LPCSTR	lpszRootPath;

  LPCSTR	lpszVirtualRoot;

  LPCSTR	lpszVolumeLabel;

  LPCSTR	lpszFSName;

  INT	iMaxNameLength;

  DWORD	dwSerialNumber;

  WORD	wDiskNum;

  WORD	wMediaType;

  INT	iBytesPerSector;

  INT	iSectorsPerCluster;

  INT	iTotalClusters;

  INT	iFreeClusters;

  INT	iNumberOfFiles;

  INT	iNumberOfCompressedFiles;

  WORD	wNumberOfDirs;

} DISKINFORECORD, FAR *LPDISKINFOREC;

Members

lpszRootPath

Points to a null-terminated string containing drive root path. This could be in either regular form (<drive>:\), or in UNC format (\\<servername>\<sharename>)

lpszVirtualRoot

Points to a null-terminated string containing drive's virtual root. Virtual root is a special feature in WhereIsIt's catalog where only a part of folder tree is catalogued, with one of the folders posing as a virtual root folder. This field will be NULL if drive does not have a virtual root, or will be in form of "\<virtual-root-path>\" (i.e. "\Virtual\Root\").

lpszVolumeLabel

Points to a null-terminated string containing drive volume label.

lpszFSName

Points to a null-terminated string containing file system name (for example: "FAT", "FAT32", "NTFS", "CDFS",...)

iMaxNameLength

Specifies the maximum length of file names allowed on this drive.

dwSerialNumber

Specifies disk's serial number.

wDiskNum

Specified user assigned disk number in the catalog.

wMediaType

Specifies media or disk type. See the Drive Types description for list of values.

iBytesPerSector

Specifies the number of bytes per sector.

iSectorsPerCluster

Specifies the number of sectors per cluster.

iTotalClusters

Specifies the number of all clusters on the media.

iFreeClusters

Specifies the number of free clusters on the media.

iNumberOfFiles

Specifies the number of files on the media, as found by the program during disk scan. If WhereIsIt was instructed to skip some files, this number may be lower than the actual number of files on disk. The content of compressed archive files is not included in this count.

iNumberOfCompressedFiles

Specifies the number of compressed files successfully retrieved from archive files during disk scan.

wNumberOfDirs

Specifies the number of folders on the media, as found by the program during disk scan. If WhereIsIt was instructed to skip some folders, this number may be lower than the actual number of folders on disk.

See also:

ImportDesc_DiskInfo